package it.traveldream.beans;

import it.traveldream.dto.LocationDTO;
import it.traveldream.dto.ProductDTO;
import it.traveldream.dto.ProductTypeDTO;
import it.traveldream.exceptions.InvalidProductException;
import it.traveldream.exceptions.LocationNotFoundException;
import it.traveldream.exceptions.ProductNotFoundException;

import java.util.List;

import javax.ejb.Local;

/**
 * 
 * @author Flavio Ferrara
 * <p>
 * ProductManagerInterface declares and describes available functions that the client can call
 * in order to handle basic products.
 * There exists various kind of products, so the interface is declared by using Generics.
 * It will be required to extend this interface with a specific one for each kind of product. 
 * 
 * This interface will NOT be implemented by any Enterprise Java Beans.
 */

@Local
public interface ProductManagerInterface<T extends ProductDTO> {

	/**
	 * Returns a list containing the existing types of products. 
	 * @return List of product types
	 */
	public List<ProductTypeDTO> getProductTypes();
	
	/**
	 * Returns a list containing products of any type, located in the 
	 * specific location passed as argument.
	 * @param location The location to be searched for.
	 * @return List of product items. Each item specifies, at least, product ID, name and type.
	 * @throws LocationNotFoundException
	 */
	public List<ProductDTO> getProductsByLocation(LocationDTO location) throws LocationNotFoundException;
	
	/**
	 * Return information about a specific product.
	 * The argument must contain a valid value for product ID field.
	 * @param product The product to be searched for.
	 * @return A representation, containing type-specific data, of the product.
	 * @throws ProductNotFoundException
	 */
	public T getProduct(ProductDTO product) throws ProductNotFoundException;
	
	/**
	 * Records in Persistence tier information about a product.
	 * The argument must contain valid values for name field.
	 * The client is not required to provide an ID as argument. If the argument 
	 * contains any value, it will be ignored and replaced with an auto-generated one.
	 * @param product A representation, containing type-specific data, of the product.
	 * @throws InvalidProductException
	 * @return A representation, containing type-specific data, of the product, with 
	 * 	generated product ID.
	 */
	public T saveProduct(T product) throws InvalidProductException;
	
	/**
	 * Updates in Persistence tier information about an existing product.
	 * The argument must contain a valid value for product ID field.
	 * @param product A representation, containing type-specific data, of the product.
	 * @throws ProductNotFoundException
	 * @throws InvalidProductException
	 */
	public void updateProduct(T product) throws ProductNotFoundException, InvalidProductException;
	
	/**
	 * Deletes from Persistence tier an existing product.
	 * The argument must contain a valid value for product ID field.
	 * @param product A representation, containing type-specific data, of the product.
	 * @throws ProductNotFoundException
	 */
	public void deleteProduct(T product) throws ProductNotFoundException;
}
